home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / mig.h < prev    next >
C/C++ Source or Header  |  1990-07-05  |  16KB  |  421 lines
  1. /*
  2.  * mig.h --
  3.  *
  4.  *    Declarations of structures, constants, and procedures to manage
  5.  *    the global database of host load averages and uptimes.
  6.  *
  7.  * Copyright 1987, 1988, 1989, 1990 Regents of the University of California
  8.  * Permission to use, copy, modify, and distribute this
  9.  * software and its documentation for any purpose and without
  10.  * fee is hereby granted, provided that the above copyright
  11.  * notice appear in all copies.  The University of California
  12.  * makes no representations about the suitability of this
  13.  * software for any purpose.  It is provided "as is" without
  14.  * express or implied warranty.
  15.  *
  16.  * $Header: /sprite/src/lib/include/RCS/mig.h,v 1.15 90/05/16 11:51:27 douglis Exp $ SPRITE (Berkeley)
  17.  */
  18.  
  19. #ifndef _MIG
  20. #define _MIG
  21.  
  22. #include <fs.h>
  23.  
  24. /*
  25.  * We keep track of 1, 5, and 15-minute load averages in the database.
  26.  * We sample the load every MIG_LOAD_INTERVAL seconds and update it
  27.  * in the global daemon's database at least every MIG_GLOBAL_UPDATE_INTERVAL
  28.  * seconds.  A host is considered "down" if it hasn't updated within
  29.  * MIG_TIMEOUT seconds.
  30.  */
  31. #define MIG_NUM_LOAD_VALUES 3
  32. #define MIG_LOAD_INTERVAL 5
  33. #define MIG_GLOBAL_UPDATE_INTERVAL (12 * MIG_LOAD_INTERVAL)
  34. #define MIG_TIMEOUT (3 * MIG_GLOBAL_UPDATE_INTERVAL)
  35.  
  36. /*
  37.  * Constants affecting how hard and how often processes will try to
  38.  * contact the global daemon.  A process should sleep 1 second, try
  39.  * again, and then double the time it sleeps until it has tried
  40.  * MIG_DAEMON_RETRY_COUNT times.  2**5 is just about 30 seconds.
  41.  */
  42.  
  43. #define MIG_DAEMON_RETRY_COUNT 5
  44.  
  45. /* 
  46.  * Host states:
  47.  *
  48.  *    MIG_HOST_ACTIVE        - Host has active user, or a high load from
  49.  *                  local processes.
  50.  *    MIG_HOST_IDLE        - Host is completely idle, with no foreign
  51.  *                  processes.
  52.  *    MIG_HOST_PART_USED    - Host is being used by some processes,
  53.  *                  but still has capacity for foreign procs.
  54.  *    MIG_HOST_FULL        - Host is completely used by the highest
  55.  *                  priority processes but would otherwise
  56.  *                  accept foreign processes.
  57.  *    MIG_HOST_REFUSES    - Host refuses all migrations.
  58.  *    MIG_HOST_DOWN        - Host is not running or is unreachable.
  59.  *
  60.  * These states are associated with hosts; processes have priorities
  61.  * based on the ones defined in proc.h (PROC_HIGH/NORMAL/LOW_PRIORITY),
  62.  * but 0-based.  We also define a constant for indexing among these priorities.
  63.  */
  64. #define    MIG_HOST_ACTIVE        0
  65. #define    MIG_HOST_IDLE        1
  66. #define    MIG_HOST_PART_USED    2
  67. #define    MIG_HOST_FULL        3
  68. #define    MIG_HOST_REFUSES    4
  69. #define    MIG_HOST_DOWN        5
  70. #define MIG_NUM_STATES         (MIG_HOST_DOWN + 1)
  71.  
  72. #define MIG_LOW_PRIORITY     0
  73. #define MIG_NORMAL_PRIORITY     1
  74. #define MIG_HIGH_PRIORITY     2
  75. #define MIG_NUM_PRIORITIES     (MIG_HIGH_PRIORITY + 1)
  76.  
  77. /*
  78.  * For each machine, keep track of the timestamp for its information, various
  79.  * load averages, and info about idle time and foreign processes.
  80.  * The following structures define the way this information is used.
  81.  * A Mig_LoadVector is the load information that varies from time to time.
  82.  * This info is updated by the loadavg daemons and may be used by widgets or
  83.  * other programs that periodically sample the load average.  Other information
  84.  * is more static -- it won't change after a host boots, or it changes
  85.  * independent of the loadavg daemon (for example, when a host is used
  86.  * for migration).
  87.  */
  88.  
  89. /*
  90.  ********************************************************************
  91.  *                   IMPORTANT NOTE                 *
  92.  ********************************************************************
  93.  *                                    *
  94.  * Changes to the structures in this file must also be reflected in *
  95.  * the Fmt format strings used by the migration server.            *
  96.  *                                    *
  97.  ********************************************************************
  98.  */
  99.  
  100. typedef struct {
  101.     int     timestamp;            /* when info last updated */
  102.     int     noInput;            /* time since last input */
  103.     int        allowMigration;            /* host allowing migration? */
  104.     int        foreignProcs;            /* total number of foreign
  105.                            processes recorded
  106.                            by kernel */
  107.     int        utils[MIG_NUM_LOAD_VALUES];    /* avg utilizations (in %) */
  108.     int        pad;                /* pad structures */
  109.     double    lengths[MIG_NUM_LOAD_VALUES];    /* avg ready-queue lengths */
  110. } Mig_LoadVector;
  111.  
  112. typedef struct {
  113.     int        hostID;            /* host for which info valid */
  114.     int     bootTime;        /* when host last rebooted  */
  115.     int        migVersion;        /* migration version level of
  116.                        kernel */
  117.     int        maxProcs;        /* maximum number of foreign
  118.                        processes */
  119.     int        foreign[MIG_NUM_PRIORITIES];
  120.                         /* number of foreign
  121.                        jobs currently assigned to this
  122.                        host, for each priority */
  123.     int        state;            /* state of the host w.r.t.
  124.                        migration: see above. */
  125.     int        pad[4];            /* for future expansion */
  126.     Mig_LoadVector loadVec;        /* updated periodically by loadavg
  127.                        daemon */
  128. } Mig_Info;
  129.  
  130.  
  131. /*
  132.  * Define structures and constants for interfacing with the daemons using
  133.  * pdevs.
  134.  */
  135.  
  136. /*
  137.  * IOControls for communication between Mig lib and global migration daemon
  138.  *    IOC_MIG_GETINFO        - return Mig_Info for one or more hosts.
  139.  *    IOC_MIG_GETIDLE        - get idle host(s).
  140.  *    IOC_MIG_DONE        - return idle host(s) to free pool.
  141.  *    IOC_MIG_KILL        - remove load value(s) from database.
  142.  *    IOC_MIG_DAEMON        - flags process as a loadavg daemon
  143.  *                   and initializes load information.
  144.  *    IOC_MIG_CHANGE        - daemon is changing host status.
  145.  *    IOC_MIG_GET_PARAMS     - get system parameters.
  146.  *    IOC_MIG_SET_PARAMS     - set system parameters (must be root).
  147.  *    IOC_MIG_GET_STATS     - get statistics.
  148.  *    IOC_MIG_GET_UPDATE     - get update on host availability.
  149.  *    IOC_MIG_EVICT        - force all processes to be evicted.
  150.  *    IOC_MIG_RESET_STATS     - reset statistics.
  151.  */
  152.  
  153. #define IOC_MIG_GETINFO        (IOC_GENERIC_LIMIT+1)
  154. #define IOC_MIG_GETIDLE         (IOC_GENERIC_LIMIT+2)
  155. #define IOC_MIG_DONE            (IOC_GENERIC_LIMIT+3)
  156. #define IOC_MIG_KILL            (IOC_GENERIC_LIMIT+4)
  157. #define IOC_MIG_DAEMON        (IOC_GENERIC_LIMIT+5)
  158. #define IOC_MIG_CHANGE          (IOC_GENERIC_LIMIT+6)
  159. #define IOC_MIG_GET_PARAMS      (IOC_GENERIC_LIMIT+7)
  160. #define IOC_MIG_SET_PARAMS      (IOC_GENERIC_LIMIT+8)
  161. #define IOC_MIG_GET_STATS    (IOC_GENERIC_LIMIT+9)
  162. #define IOC_MIG_GET_UPDATE    (IOC_GENERIC_LIMIT+10)
  163. #define IOC_MIG_EVICT        (IOC_GENERIC_LIMIT+11)
  164. #define IOC_MIG_RESET_STATS    (IOC_GENERIC_LIMIT+12)
  165. #define IOC_MIG_LASTCMD        IOC_MIG_RESET_STATS
  166.  
  167. /*
  168.  * IOC_MIG_GETINFO -
  169.  * For requesting information about host statuses.  Returns the number
  170.  * of hosts for which information is returned, followed by an array of
  171.  * Mig_Info structures.  The data returned are not aligned as though
  172.  * they were in a structure; therefore, the caller may need to bcopy
  173.  * from a character buffer into a structure to make use of the data.
  174.  * The normal interface to get this info is via the library routine
  175.  * Mig_GetAllInfo or Mig_GetInfo, which get the Mig_Info structures
  176.  * for many hosts or a single host, respectively [due to historical
  177.  * reasons].
  178.  */
  179.  
  180. typedef struct {
  181.     int firstHost;        /* ID of first host requested. */
  182.     int numRecs;        /* Number of entries requested. */
  183. } Mig_InfoRequest;
  184.  
  185.  
  186. /*
  187.  * IOC_MIG_GETIDLE -
  188.  *
  189.  * For requesting idle hosts.  Returns the number of hosts assigned followed
  190.  * by the numeric identifiers of the hosts.
  191.  */
  192.  
  193. typedef struct {
  194.     int numHosts;        /* Number of hosts requested. */
  195.     int flags;            /* Flags, defined below. */
  196.     int priority;        /* Priority of processes, defined above. */
  197.     int    virtHost;        /* Virtual host of process making request. */
  198. } Mig_IdleRequest;
  199.  
  200. /*
  201.  * Flags for foreign processes:
  202.  *
  203.  *     MIG_PROC_RELOCATE    - Wish to relocate if evicted.
  204.  *     MIG_PROC_AGENT        - Request is on behalf of another process.
  205.  *                  Do not reclaim host because process that
  206.  *                  makes the request closes its connection.
  207.  */
  208.  
  209. #define MIG_PROC_RELOCATE    0x0001
  210. #define MIG_PROC_AGENT        0x0002
  211.  
  212.  
  213. /*
  214.  * IOC_MIG_DONE -
  215.  *
  216.  * For returning idle hosts to the pool, or removing hosts from the database,
  217.  * An array of hostIDs is passed.  In each case, nothing is returned.
  218.  * MIG_ALL_HOSTS indicates that the operation should be performed for
  219.  * all hosts (either hosts in use for migration, or every host in the database,
  220.  * respectively).  Hosts are reclaimed implicitly if the process closes the
  221.  * pdev talking to the server (including if it exits).
  222.  */
  223.  
  224. #define MIG_ALL_HOSTS 0
  225.  
  226. /*
  227.  * IOC_MIG_GET_UPDATE -
  228.  *
  229.  * For getting updates to host availability.  The caller is responsible
  230.  * for making as many ioctls as needed until the stream is not selectable,
  231. x * since only a single update is transferred with each ioctl. (Normally
  232.  * only one is necessary.)
  233.  *
  234.  * There is no input for this ioctl. The output is an integer specifying
  235.  * a host that is no longer available, or 0, indicating that a new
  236.  * host is available and IOC_MIG_GET_IDLE should be used to get a new
  237.  * host.
  238.  */
  239.  
  240. /*
  241.  * IOC_MIG_GET_STATS -
  242.  * IOC_MIG_RESET_STATS -
  243.  *
  244.  * GET_STATS returns a structure, defined below.  RESET_STATS takes and
  245.  * returns no arguments.
  246.  *
  247.  * Define the structure used to maintain statistics for migration.  Note
  248.  * that changes to these structures must be reflected in the byte-swapping
  249.  * constants used by the migration daemon.
  250.  *
  251.  * Define the maximum number of architecture types we'll
  252.  * keep statistics about, and statistics that are kept track of on a
  253.  * per-machine-type basis.
  254.  *
  255.  * MIG_MAX_ARCH_TYPES     - maximum number of architectures managed by migd.
  256.  *            - This can be increased, but only by complicating
  257.  *              the interface to obtain statistics so it can
  258.  *              transfer the buffer in pieces.
  259.  * MIG_MAX_ARCH_LEN     - maximum length of a string used in stats.
  260.  * MIG_MAX_HOSTS_DIST     - maximum number of hosts in a request that we'll keep
  261.  *              track of (i.e. last element of array is this many
  262.  *              or more).
  263.  * MIG_INTERVAL_PERIOD  - number of seconds between incrementing counters
  264.  * MIG_STATS_VERSION    - version of statistics structure, to catch
  265.  *              inconsistencies.
  266.  */
  267.  
  268. #define MIG_MAX_ARCH_TYPES 8
  269. #define MIG_MAX_ARCH_LEN 12
  270. #define MIG_MAX_HOSTS_DIST 20
  271. #define MIG_INTERVAL_PERIOD 300
  272. #define MIG_STATS_VERSION 5
  273.  
  274.  
  275. /*
  276.  * Statistics that are kept as a sum and as a sum of squares (for standard
  277.  * deviation).  The ones that are likely to overflow are kept as two
  278.  * integers and a macro is used to add to them.
  279.  */
  280.  
  281. #define MIG_COUNTER_HIGH 1
  282. #define MIG_COUNTER_LOW 0
  283.  
  284. typedef struct {
  285.     unsigned int requested;        /* Number of hosts requested. */
  286.     unsigned int obtained;        /* Number of hosts obtained. */
  287.     unsigned int evicted;        /* Number of hosts taken back from
  288.                        client due to eviction. */
  289.     unsigned int reclaimed;        /* Number of hosts taken back from
  290.                        client due to other causes
  291.                        (e.g., fairness). */
  292.     unsigned int timeUsed;        /* Total time before returning hosts,
  293.                        in seconds. */
  294.     unsigned int timeToEviction;    /* Total time before evictions occur. */
  295.     unsigned int hostIdleObtained[2];    /* Idle time of hosts obtained when
  296.                        assigned, in minutes. */
  297.     unsigned int hostIdleEvicted[2];    /* Idle time of hosts at time they are
  298.                        assigned, just for those hosts that
  299.                        later evict processes. */
  300.     unsigned int idleTimeWhenActive[2];    /* The amount of time hosts were idle
  301.                        when they became non-idle. */
  302.     unsigned int hostCounts[MIG_NUM_STATES]; /* Number of hosts in each
  303.                         state. */
  304.     int pad[2];                /* Pad to double-word boundary. */
  305. } Mig_StatTotals;
  306.  
  307. typedef struct {
  308.     char arch[MIG_MAX_ARCH_LEN];    /* String representation of machine
  309.                        type. */
  310.     unsigned int numClients;        /* Number of processes requesting
  311.                        hosts. */
  312.     unsigned int gotAll;        /* Number of processes getting as
  313.                        many hosts as requested. */
  314.     unsigned int requestDist[MIG_MAX_HOSTS_DIST + 1];
  315.                         /* Distribution of maximum number of
  316.                        hosts requested. */
  317.     unsigned int obtainedDist[MIG_MAX_HOSTS_DIST + 1];
  318.                         /* Distribution of maximum number of
  319.                        hosts obtained. */
  320.     unsigned int nonIdleTransitions;    /* Number of times hosts went from
  321.                        idle to non-idle. */
  322.     Mig_StatTotals counters;        /* Counters of different types of
  323.                        operations, cumulative. */
  324.     Mig_StatTotals squared;        /* Sum of Squares of above counters
  325.                        (for calculating std. dev.). */
  326. } Mig_ArchStats;
  327.  
  328. typedef struct {
  329.     unsigned int version;        /* Version number of the daemon. */
  330.     unsigned int checkpointInterval;    /* Interval for checkpointing (and
  331.                        incrementing counters). */
  332.     unsigned int firstRun;        /* Time when statistics first started
  333.                        gathering. */
  334.     unsigned int restarts;        /* Number of times the daemon
  335.                        restarted. */
  336.     unsigned int intervals;        /* Number of intervals over which
  337.                        statistics have been gathered. */
  338.     unsigned int maxArchs;        /* Maximum number of architecture
  339.                        types we know about. */
  340.     unsigned int getLoadRequests;    /* Number of times clients asked for
  341.                        load info. */
  342.     unsigned int totalRequests;        /* Total number of times hosts were
  343.                        requested. */
  344.     unsigned int totalObtained;        /* Total number of times hosts were
  345.                        assigned. */
  346.     unsigned int numRepeatRequests;    /* Number of times the requesting host
  347.                        was the same as the previous
  348.                        request. */
  349.     unsigned int numRepeatAssignments;    /* Number of times the same
  350.                        <physical,virtual> host pair was
  351.                        assigned twice in a row. */
  352.     unsigned int numFirstAssignments;    /* Number of assignments that were
  353.                        to hosts that hadn't been assigned
  354.                        to anyone since going idle.*/
  355.     Mig_ArchStats archStats[MIG_MAX_ARCH_TYPES]; /* Per-architecture stats. */
  356. } Mig_Stats;    
  357.  
  358.  
  359. /*
  360.  * IOC_MIG_KILL          - sends int.
  361.  * IOC_MIG_DAEMON     - sends Mig_Info structure.
  362.  * IOC_MIG_CHANGE      - sends int.
  363.  * IOC_MIG_EVICT      - receives int.
  364.  */
  365.  
  366. /*
  367.  * IOC_MIG_GET_PARAMS -
  368.  * IOC_MIG_SET_PARAMS -
  369.  *
  370.  * Define the parameters used by the migration daemons.  This can be
  371.  * updated or obtained via an ioctl.  If the global daemon is updated
  372.  * then it notifies the other daemons to retrieve the new parameters.
  373.  * One can also connect to the local daemon and modify the info for a
  374.  * particular host.  The migration version and criteria are not
  375.  * broadcast from the global server.  
  376.  *
  377.  * The criteria for allowing migration, unless overridden, are idle
  378.  * time (noInput) and ready queue lengths.  If we are not allowing
  379.  * foreign processes, but our time since last input is greater than
  380.  * noInput and our average queue lengths are ALL less than the
  381.  * corresponding values in min, start accepting foreign processes.  If
  382.  * we are allowing foreign processes and either the idle time drops or
  383.  * ANY of the average queue lengths exceeds its corresponding value in
  384.  * max, stop accepting them.
  385.  */
  386.  
  387. typedef struct {
  388.     int        criteria;            /* Whom to allow, and when
  389.                            (c.f. proc.h). */
  390.     int        version;            /* Migration version. */
  391.     int        noInput;            /* Idle time needed. */
  392.     int        pad;                /* Fill out to doubleword. */
  393.     double    minThresh[MIG_NUM_LOAD_VALUES];    /* Minimum load before
  394.                            becoming idle */
  395.     double    maxThresh[MIG_NUM_LOAD_VALUES];    /* Maximum load before
  396.                            refusing migrations once
  397.                            idle. */
  398. } Mig_SystemParms;
  399.  
  400.  
  401. /* 
  402.  * Declare the global variables that refer to the pdevs used.  
  403.  */
  404. extern int mig_GlobalPdev;     
  405. extern int mig_LocalPdev;
  406.  
  407.  
  408. extern Mig_Info *    Mig_GetInfo();
  409. extern int         Mig_GetAllInfo();
  410. extern int         Mig_GetIdleNode();
  411. extern int         Mig_OpenInfo();
  412. extern int         Mig_UpdateInfo();
  413. extern int         Mig_Done();
  414. extern int         Mig_ConfirmIdle();
  415. extern int         Mig_DeleteHost();
  416. extern int         Mig_Evict();
  417. extern char *         Mig_GetPdevName();
  418. extern int         Mig_OpenPdev();
  419.  
  420. #endif /* _MIG */
  421.